CaptureComponent

CaptureComponent
Header:	Components.h		Carbon status:	Supported

Allows your component to capture another component.

Component CaptureComponent (
    Component capturedComponent, 
    Component capturingComponent
);

Parameter descriptions

capturedComponent: The component to be captured. Your component can obtain this identifier from the FindNextComponent function or from the component registration functions. You can use a component instance here, but you must coerce the data type appropriately.
capturingComponent: Your component. Note that you can use the component instance (appropriately coerced) that your component received in its open request in this parameter.

function result: A new component identifier. Your component can use this new identifier to refer to the captured component. For example, your component can open the captured component by providing this identifier to the OpenComponent structure. Your component must provide this identifier to the UncaptureComponent function to specify the component to be restored to the search list. If the component you wish to capture is already captured, the component identifier is set to NULL.

DISCUSSION

Typically, your component captures another component when you want to override all or some of the features provided by a component or to provide new features. For example, a component called NewMath might capture a component called OldMath. Suppose the NewMath component provides a new function, DoExponent. Whenever NewMath gets an exponent request, it can handle the request itself. For all other requests, NewMath might call the OldMath component to perform the request.

After capturing a component, your component might choose to target a particular instance of the captured component.

In response to this function, the Component Manager removes the specified component from the list of available components. As a result, applications cannot retrieve information about the captured component or gain access to it. Current clients of the captured component are not affected by this function.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.